Back to Contents        Previous        Next






23. Window & Icon creation

Why ‘create’ when you can use templates?
Normally, it makes sense to use window templates to create windows and icons - and load them into a program as we have done so far. The !WinEd and !TemplEd utilities allow you to create your windows/icons in this way and both are included in the Dr Wimp package.

However, there can sometimes be advantages in creating windows and icons directly from Basic within your !RunImage instead. For instance, to display search results dynamically when you may not know at the start of the program how many icons are needed. Or, from a security point of view, if you secure your Basic code then no-one can change the windows and icons.

To meet this need, DrWimp provides four functions for creating and deleting windows and icons directly, and these will shortly be described in detail.

Also, a wimp-function is provided to plot an icon directly to a redraw window without becoming part of the window definition. This is PROCwimp_ploticon() - see later.

But be warned! The depth of detail about the Wimp in this topic is necessarily more than is usual in Dr Wimp. But if it starts to bemuse you, Don’t Panic! There is a further Dr Wimp utility called !CodeTemps which does it all for you and eliminates the detail - see later.

‘Flags’
The direct creation of windows and icons requires - apart from several other parameters - the use of flags to describe certain aspects of the window or icon to be created. Before looking at the particular cases it is worth diverting for a moment to describe how Dr Wimp implements these flags.

Each flag is represented by one bit - either ‘set’ or ‘unset’ (1 or 0 respectively). Several flags can therefore be represented together by a multi-bit combination, such as a byte (8-bits, giving space for 8 flags). Of course, such a flag/bit pattern looks exactly the same as a single integer number and so the number can represent the flags collectively, and be passed as a parameter to the creating wimp­function.

To demonstrate this, let us assume that we have 8 flags - each of 1-bit. Thus, if we used bits 0-7 of a conventional byte to hold the 8 values, we might produce a byte looking like this, for example:

00101101

Here, reading the bits (conventionally) from right to left, Bit 0 represents ‘flag0’ (which is ‘set’, i.e. =1); Bit 1 represents ‘flag1’ (which is ‘unset’, i.e. =0); etc.

This same sequence of bits is also a binary number. So the above example has bits 0, 2, 3 and 5 set (value=1), and the rest unset (value=0).

In BASIC, this binary number would be represented as:

%00101101

or, of course, could equally well be expressed as:

         45 in decimal,
or         &2D in hexadecimal.

So, in Basic, any one of these numbers can be passed as the flags parameter to the wimp-functions, as they all represent the same bit pattern. (You may find the binary format easiest to use as you can quickly work out which individual flags are set and unset - and we will use this form below.)
With this introductory material finished, we can start to look at the particular wimp-functions involved. For various reasons, it makes sense to look at icon creation before window creation - not in the least because, in practice, the need to create icons tends to occur more frequently than the need for window creation.

Creating icons
The wimp-function used to create icons is:

icon%=FNwimp_createicon(window%,wminx%,wminy%,wmaxx%,wmaxy%, flags%,esg%,button%,fcol%,bcol%,font%, text$,sprname$,sarea%,maxind%,valid$)

(With 16 parameters, it is one of the longest wimp-functions in the DrWimp library - and necessarily requires a bit more knowledge of wimp programming than is usual for DrWimp.)

window% is the handle of the window to create the icon in. wminx%, wminy%, wmaxx%, wmaxy% are the work area coordinates that define the position of the icon and its size. For example using 8,-48,48,-8 will create an icon that is 8 OS units in from the left edge of the window, 8 OS units down from the top edge, and 40x40 OS units in size. Remember that the y-values will normally both be negative, if the icon is to appear wholly within the window.

flags% is a 15-bit number that represents most of the Wimp’s ‘icon flags’ for the icon. The flags used by Dr Wimp are:
        
         bit:         meaning if set:

         0         icon has text
         1         icon has sprite
         2         icon has border
         3         text/sprite is horizontally centred
         4         text/sprite is vertically centred
         5         icon is filled
         6         icon uses an outline font
         7         icon requires task’s help to be redrawn
         8         icon is indirected
         9         text/sprite is right justified
         10         <adjust> does not cancel other selected icons in same ESG
         11         display the sprite (if any) half-size
         12         icon is displayed as ‘selected’
         13         icon is disabled i.e. greyed out and cannot be ‘selected’
         14         icon has been deleted

(Note that flag bits 0-11 above line up with the icon flag bits used by the Wimp - and flag bits 12-14 above line up with icon flag bits 21-23 as used by the Wimp. The remainder of the Wimp’s icon flag bits are covered by other parameters in the wimp-function.)

For example, a flags% value of:

%000000101011101

would signify an icon that (reading from right to left): has text, has a border, the text is horizontally and vertically centred, uses an outline font and the text is indirected. All other options are ‘unset’.

esg% is the Exclusive Selection Group (ESG) number for the icon, which can be in the range 0-31 inclusive. All icons with the same ESG (if greater than 0) will be treated as a group and selecting one of them will automatically deselect others in the same group. These are normally only used for radio icons. All other icon types should have the ESG set to 0.

button% is the number of the ‘button type’ of the icon. (Note that it is not in the above flag format.)

         button%         button type (what action notifies task.)
         value

         0         ignore
         1         always (task notified continuously whilst pointer is over icon)
         2         click (with auto-repeat)
         3         click (once only)
         4         release (initial click selects icon, release over icon notifies task)
         5         double-click
         6         click/drag (as 3 but, also, drag notifies task with “button state*16”)
         7         release/drag (as 4 but, also, drag notifies task with “button state*16”)
         8         double-click/drag (as 5 but, also, drag notifies task with “button state*16”)
         9         menu (pointer over icon selects, moving away deselects, click notifies task)
         10         click/double-click/drag (click notifies task with “button state*256”,
                                    drag with “button state*16”, double-click with “button state*1”)
         11         radio (click selects and notifies task with “button state*1”,
                                    drag with “button state*16”)
         12         reserved - not used
         13         reserved - not used
         14         writable/click/drag (click gives icon caret and its window gets ‘input focus’)
         15         writable (click gives icon caret and its window gets ‘input focus’)
                 
         “Button state” means:
                  1 for <adjust>
                  2 for <menu>
                  4 for <select>
                  or in combination, e.g. <adjust> + <select> gives 5.

(Note that the button numbers above line up with the button numbers used by the Wimp.)

fcol% and bcol% are the foreground and background colours of the icon in desktop colours, so they are both in the range 0-15. Usually set to 7 and 1 respectively. Ignored if the icon uses an outline font - but values must still be present.

font% is the handle of an outline font, if one is being used i.e. if Bit 6 of flags% is set. If not then this should be set to 0. (If Bit 6 of flags% is set but the value of font% is invalid for any reason, then Bit 6 will automatically be unset - but the icon will be given the default colours of an outline font i.e. Black-on-White. A warning is given.)

If the icon has some text, then it is put in text$, and if the icon has a sprite, then its name is put in sprname$. The sprite area handle is put into sarea%, with 0 denoting Wimp sprite pool.

If the icon is indirected, then maxind% is the maximum number of text characters that can be put into the icon - plus 1 for a terminator. maxind% would, of course, need to be larger than the length of text$ if it is intended that longer text might be introduced when using the application.

valid$ is the icon validation string, which may contain information such as the pointer to use for the icon, the acceptable characters for writable icons, the border type, outline font colours etc. (If a validation string is to be used - i.e. if valid$ is not a null string - then the icon must be ‘indirected’ i.e. Bit 8 of flags% must be ‘set’.)

The function returns a handle to the icon, which is the icon number.

An example, for creating a standard OK button, is:

okbutton%=FNwimp_createicon(main%,8,-76,136,-8, %000000100011101,0,1,7,1,0,“OK”,“”,0,3,“R6,3”)



Creating windows
As said earlier, the wimp-function to create windows is likely to be less used, but here it is:

window%=FNwimp_createwindow(vminx%,vminy%,vmaxx%,vmaxy%,wminx%, wminy%,wmaxx%,wmaxy%,flags%,colourflags%,button%, title$,titleflags%,titlefont%,maxind%,sarea%)


vminx%, vminy%, vmaxx%, vmaxy% are the screen coordinates that describe the area of screen that the visible part of the window will cover when opened. (If you open it centred or centred on the pointer or at specific coordinates, then the position vminx% and vminy% on the screen will be ignored. However, vmaxx%-vminx% and vmaxy%-vminy% set the width and height of the window.) The visible area has to be less than the work area. A window cannot be opened larger than its work area!

wminx%, wminy%, wmaxx%, wmaxy% are the work area coordinates that set the work area of the window. For example setting them to 0, -100, 200, 0 will create a window whose work area is 200x100 in size (remember that the work area origin is at the top left so work area y-values are always negative).

flags% is a 17-bit number that represents the ‘window flags’ for the window.

         bit:         meaning if set:

         0         window has title bar
         1         window has close icon
         2         window has back icon
         3         window has horizontal scroll bar
         4         window has vertical scroll bar
         5         window has adjust size icon
         6         window has toggle size icon
         7         window can auto-redraw (i.e. no user graphics in window)
         8         window is a pane
         9         window is moveable
         10         window can be opened/dragged outside screen
         11         ‘Scroll Event’ will be generated (with auto-repeat)
         12         ‘Scroll Event’ will be generated (without auto-repeat)
         13         ‘Hot key Events’ will be generated
         14         window forced to stay on screen
         15         dragging ‘adjust size’ icon ignores right-hand extent of window
         16         dragging ‘adjust size’ icon ignores lower extent of window

(Note that the flag bits above are in a different order to the bit positions used by the Wimp. This is because the latter are not in a convenient sequential order. However, all options provided by the Wimp are provided.)

For example, a flags% value of:

%00000001011111001

would signify a window which has (reading from right to left) a title bar, no close icon, no back icon, has horizontal and vertical scroll bars, has an adjust size icon, has a toggle size icon, does auto-redraws (i.e. PROCuser_redraw isn't called), isn't a pane, is moveable - and has none of the bits of the more esoteric flags 10-16 set. (Remember that the pane item does not affect Dr Wimp’s ability to use a window as a pane.)

colourflags% allows the colours of all items of a window’s ‘furniture’ to be specified. There are seven items, as follows - with their standard (Style Guide) colours shown in brackets:

Title foreground (7)
Title background (2)
Work area foreground (7)
Work area background (1)
Scroll bar outer (3)
Scroll bar inner (slider) (1)
Title background when highlighted for input focus (12)

Each item is specified by choosing its colour in the Wimp range of 0-15 and arranging these colour naumbers in the above order from left to right to give a single hex number. Thus the value of colourflags% to produce the standard Wimp colours is &727131C.



button% is the ‘button type’ number of the window. Essentially, it follows the button types used for creating icons (see earlier in this section) - except that, with windows, there is no concept of a window being ‘selected’ and simply refers to the <select> or <adjust> button actions. (<menu> clicks in a window are always reported to the task.)

title$ is the title of the window. If it is longer than 11 characters then the title will automatically become indirected (see titleflags% below).

titleflags% is an 8-bit number representing the ‘Title bar flags’ for the window. They are basically similar to ‘icon flags’ (see earlier in this section) - except that only a sub-set of them is involved, and hence not so many bits are needed
.
         bit:         meaning if set:

         0         title has text
         1         title has sprite
         2         text/sprite is horizontally centred
         3         text/sprite is vertically centred
         4         title uses an outline font
         5         text/sprite is right justified
         6         sprite (if used) is displayed half-size
         7         title is indirected (will also be set automatically if title$ exceeds 12 characters)

titlefont% is the handle of the outline font for the title text, if one is being used i.e. if Bit 4 of titleflags% is set. If not then this should be set to 0. (If Bit 4 of titleflags% is set but the value of titlefont% is invalid for any reason, then Bit 4 will automatically be unset. A warning is given.)

If the title is indirected, then maxind% is the maximum size that the title can be, plus 1 for a terminator.

If sarea% is 0 then the Wimp sprite pool is used for the window, otherwise sarea% is the handle of a sprite area (just the same as in FNwimp_loadwindow).

As with its icon-generating counterpart, the wimp-function returns a handle - in this case, the window handle.


An example of a simple window is:

main%=FNwimp_createwindow(406,572,790,816,0,-936,1236,0,
                           %00000001011111001,&727131C,0,“main”,%10001101,0,7,0)

which would create a window with a visible area in the rectangle with corners at 406, 572 and 790, 816 with respect to the bottom left corner of the screen. The window’s work area is 1236 by 936 OS units. The window flags are the same as the example given earlier. The window ‘furniture’ has standard colours and the button type is 0 (’ignore’). The window title is “main” and the title flags are represented by %10001101 (i.e. text, horizontally and vertically centred, indirected - no outline font, so titlefont% is set to 0). The max indirected text length is 7 (6 chars + 1 terminator) and the wimp area is left as the default 0 as no sprites are used in the creation.



!CodeTemps utility
Although the above processes are straightforward, they can be tedious and therefore prone to typing errors. This is where the !CodeTemps utility will make a huge difference. (It is in the Utils folder, supplied with DrWimp.)

With !CodeTemps you can combine the convenience of using window templates with the wish to create windows/icons from within the program. !CodeTemps converts window templates containing icons into the exact Basic calls to reproduce them with FNwimp_createwindow and FNwimp_createicon - plus FNwimp_getfont if outline fonts are used anywhere.

!CodeTemps is very easy to use - essentially ‘drag & drop’ - and instructions are contained in its !Help file.


Other points
Here are some further points:
Windows - however created - may be deleted (i.e. their definition removed from the application) using:


PROCwimp_deletewindow
(main%)


which will delete the window whose handle is
main%
. If the window was open then it will be closed. One point to note though is that not all memory used by the window is immediately released. The memory used to store indirected data remains tied up for the run of the program, so a large amount of creating and deleting windows will eventually result in running out of memory.


Similarly, icons can be deleted using
PROCwimp_deleteicon
, for example:


PROCwimp_deleteicon
(main%,2,0)


will delete icon 2 from the window
main%
. The icon will not necessarily disappear immediately though. It will be deleted at the next redraw. This can be forced by setting the third parameter of
PROCwimp_deleteicon
to 1, to cause a redraw. Eg
:

PROCwimp_deleteicon
(main%,2,1)

This redraw action is targetted on the area of the icon only, rather than the whole window.

It is worth noting that you can create an icon with
zero width/height
, which can sometimes be of use. But if, in this state, you want it disappear completely from the screen, make sure it is un-filled and has no border.
If you create windows/icons be careful to ensure that the value of wimpmem% in the call to FNwimp_initialise() is large enough to cope with the additions. See Section 2.34.


Plotting icons directly
A wimp-function exists to allow icons to be defined and plotted directly to an open redraw window. The wimp-function is:

PROCwimp_ploticon(wminx%,wminy%,wmaxx%,wmaxy%, flags%,esg%,button%,fcol%,bcol%,font%, text$,sprname$,sarea%,maxind%,valid$)


Not surprisingly perhaps, it has exactly the same parameters as FNwimp_createicon(), apart from not needing the latter’s first parameter window%. Accordingly, all the meanings of the parameters are as described earlier for FNwimp_createicon().

Therefore, the utility !CodeTemps can again be used to obtain the particular values for an icon defined in a window template. In this case, however, you will need to copy the parameters from the !CodeTemps output listing without using the window% value.

PROCwimp_ploticon() will plot an icon (defined by its parameters) directly into a window which is currently being redrawn. So it is intended to be called only from within PROCuser_redraw(), with coding such as:
DEF PROCuser_redraw(window%,minx%,miny%,maxx%,maxy%, printing%,page%)
CASE window% OF
WHEN main%
PROCwimp_ploticon(........................)
ENDCASE
ENDPROC


Any icons directly plotted in this way do not become part of the window’s definition and will not have any identifying icon handle (which also explains why the call is a PROC rather than a FN). Therefore they cannot be manipulated further using the other wimp-functions such as PROCwimp_puticontext() etc.

But there is nothing to stop you making directly-plotted icons appear/disappear or to replace them with different icons etc. Many possibilities are available using ordinary Basic coding to, say, switch the plotting on/off or to plot different icons for different purposes in the same place. The Example application !IconPlot demonstrates simple switching on/off.

It is worth noting that - just like plotted redraw user-graphics/text - icons plotted this way are displayed ‘underneath’ icons which are within the window’s definition.







Top of page        Back to Contents        Previous        Next